上一篇已經嘗試了在 Github Aictions 上建立 CI/CD 流程，若團隊以 GitLab 作為主要的開發與協作平台，我們同樣可以打造對應的自動化流程，現在，就讓我們一步步了解如何在 GitLab 上實作吧！

新增.yml 檔案

不同於 Github 將 .yml 放在 .github/workflows 資料夾底下，GitLab 會檢查 project 內是否含有 .gitlab-ci.yml 檔案，並且預設放在根目錄底下，找到檔案後會依據其中配置建立 CI/CD pipeline。

💡 Tips：
如果想將 .gitlab-ci.yml 命名為其他名稱，或放在不同資料夾中，記得要到 GitLab 專案設定裡更新 CI/CD 設定檔的路徑。

最小可行 CI/CD 配置

主要步驟皆與建立 Github Aictions 相同，最大不同之處在於 .yml 內容，我們先將以下內容加入檔案內並推上 GitLab：

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.55.1-noble
  script:
    - npm ci
    - npx playwright install --with-deps
    - npx playwright test

準備好後推上 GitLab 即可看見 pipeline 正在執行：

.yml 設定檔內容

1. 定義 pipeline 的階段（stage）清單，後面的 job 必須指定屬於其中一個階段，目前只建立 test 一個階段

   stages:
     - test
   

2. 定義 job 名稱（任意識別字串），此 job 的所有設定都在下面縮排區塊

   tests:
     stage: test   # 屬於 stages 當中的 test job
     image: mcr.microsoft.com/playwright:v1.55.1-noble    # 執行此 job 時使用的 docker image
     script:    # 在 job 中依序執行的 shell 指令
       - npm ci    # 使用 package-lock.json 安裝套件 
       - npx playwright install --with-deps    # 安裝 Playwright 的瀏覽器與系統相依套件
       - npx playwright test    # 執行 Playwright 測試
   

產出報告並上傳至 Artifacts

接著我們讓 GitLab 在執行完測試後能夠產出報告，以下內容設定報告格式為 html，將整個產出資料夾上傳為 Artifacts，儲存路徑為 playwright-report/，並且過期時間為一星期：

  script:
    # ...
    - npx playwright test --reporter=html
  artifacts:
    when: always
    paths:
      - playwright-report/
    expire_in: 1 week

等 pipeline 執行完畢後，就能在 Artifacts 頁面看到測試報告：

指定測試執行時機

同樣地，我們可以指定執行測試的時機，設定只有在 main 分支推送以及 MR 時執行測試：

  only:
    - main
    - merge_requests

拆分階段

如果想要如上一篇的 Github Actions，讓測試與產出報告階段分離，可以這樣設定：

1. 在 stage 加入 deploy job：

   stages:
     - test
     - deploy
   

2. 將產出 html 報告的工作留給 deploy job，test job只產出原始測試結果：

   npx playwright test --reporter=json --output=test-results/
   

3. deploy 階段設定，以前一個階段的結果產出 html 報告，並且明確指定依賴 test job：

   deploy_report:
     stage: deploy
     image: mcr.microsoft.com/playwright:v1.55.1-noble
     needs:
       - tests
     script:
       - npx playwright show-report test-results
     artifacts:
       when: always
       paths:
         - playwright-report/
       expire_in: 1 week
     only:
       - main
       - merge_requests
   

依照上述設定完成後，就能看見 pipeline 清楚分為兩個階段執行：第一階段負責測試，第二階段則利用前一階段的結果生成 html 報告。

完整程式碼：https://gitlab.com/playwright-playground/playwright-cicd

GitLab 環境下必須使用 Docker image

最後我們來談談 Github 與 GitLab 設定內容其中一個明顯差異：
在 Github 的 .yml 中只需要設定 runs-on: ubuntu-latest，就能自動擁有完整的測試環境。
而在 GitLab 當中，通常必須使用 Playwright 官方的 Docker image 才能確保環境包含必要依賴與瀏覽器。

原因在於 Github 官方提供的託管 Runner 已經預先安裝 Node.js 以及 Chrome / Firefox / WebKit 瀏覽器，因此對於大部分測試專案而言，直接使用官方 Runner 就已足夠，不需要額外用 Docker image。

💡 Tips：
Playwright 官方 Docker image 最新發佈版本可在 Microsoft Artifact Registry 上找到。

到這裡，我們已經完成了 GitLab 的 CI/CD 流程設定。當然，GitLab 還提供更多細緻的功能與設定，如果有興趣，可以參考我的隊友撰寫的兩個實用系列文：用 GitLab CI 玩轉自動化測試與佈署以及GitLab CI 2025：深入玩轉流水線與實戰紀錄。接下來，我們將用 Docker 打造輕量化的虛擬測試環境，讓校正與 Debug 流程更加輕鬆、便利。